/* 
 * Enterprise Library Extensions - DI + ORM.
 * Copyright (C) 2006
 *
 * GNU General Public License
 *
 * This program is free software; you can redistribute 
 * it and/or modify it under the terms of the GNU General Public License 
 * as published by the Free Software Foundation; either version 2 of the 
 * License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful, but 
 * WITHOUT ANY WARRANTY; without even the implied warranty of 
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 
 * See the GNU General Public License for more details.
 */
using System;
using System.Data;
using System.Collections.Generic;
using System.Text;

namespace ELE.EnterpriseLibrary.Data
{
  /// <summary>
  /// Implementations of this interface are used by implementations of <see cref="ISqlQueryBuilder"/> 
  /// to do string parsing and manipulation on text that represent SQL query. Implementation will be 
  /// specific to the SQL implementation of a RDBMS (i.e Oracle or MS SQL Server).
  /// </summary>
  public interface ISqlParser
  {

    /// <summary>
    /// Used to build an input parameter name from the settings in configuration
    /// </summary>
    /// <param name="paramName"></param>
    /// <returns></returns>
    string BuildInputParameterName(string paramName);
    /// <summary>
    /// Get a list of the input parameters found in the sql query.
    /// </summary>
    /// <param name="sqlText">The query text.</param>
    /// <returns>The list of input parameter names.</returns>
    List<string> GetInputParameterNames(string sqlText);
    /// <summary>
    /// Get a list of the output parameters in a sql query.
    /// </summary>
    /// <param name="sqlText">The query text.</param>
    /// <returns>The list of output parameter names.</returns>
    List<string> GetOutputParameterNames(string sqlText);
    /// <summary>
    /// Given a string translate to the <see cref="DbType"/> represented by it.
    /// </summary>
    /// <param name="typeString">The string to translate.</param>
    /// <returns></returns>
    DbType GetDbTypeFromString(string typeString);
    /// <summary>
    /// Given a nullable value as a string and a representation of a <see cref="DbType"/> as a string
    /// (<seealso cref="ISqlParser.GetDbTypeFromString(string)"/>) return an object that is the real
    /// nullable object to use that matches the given type.
    /// <para>As an example:</para>
    /// <code>
    /// ISqlParser parser = new MyImplementationOfSqlParser();
    /// object v = parser.GetNullableObjectValue("0", "Integer");
    /// </code>
    /// <para>After the call the object v will be of type <see cref="System.Int32"/> and will 
    /// hold the value 0.</para>
    /// </summary>
    /// <param name="nullableValue">The string representation of the nullable value.</param>
    /// <param name="typeString">The string representation of the type.</param>
    /// <returns>The actual value of the proper type translated from the given nullableValue.</returns>
    object GetNullableObjectValue(string nullableValue, string typeString);
  }
}
